.\" $Id: PAPI_event_code_to_name.3,v 1.6 2004/10/01 15:12:28 you Exp $
.TH PAPI_event_code_to_name 3 "September, 2004" "PAPI Programmer's Reference" "PAPI"

.SH NAME
.nf
PAPI_event_code_to_name \- convert a numeric hardware event code to a name.
PAPI_event_name_to_code \- convert a name to a numeric hardware event code.
.fi

.SH SYNOPSIS
.B C Interface
.nf
.B #include <papi.h>
.BI "int\ PAPI_event_code_to_name(int " EventCode ", char *" EventName ");"
.BI "int\ PAPI_event_name_to_code(char *" EventName ", int *" EventCode ");"
.fi
.B Fortran Interface
.nf
.B #include "fpapi.h"
.BI PAPIF_event_code_to_name(C_INT\  EventCode,\  C_STRING\  EventName,\  C_INT\  check )
.BI PAPIF_event_name_to_code(C_STRING\  EventName,\  C_INT\  EventCode,\  C_INT\  check )
.fi

.SH DESCRIPTION
.B PAPI_event_code_to_name(\|)
is used to translate a 32-bit integer PAPI event code into an ASCII PAPI event name.
Either Preset event codes or Native event codes can be passed to this routine.
Native event codes and names differ from platform to platform.

.B PAPI_event_name_to_code(\|)
is used to translate an ASCII PAPI event name into an integer PAPI event code.

.SH ARGUMENTS
.I EventName
-- a string containing the event name as listed in
.BR PAPI_presets(3)
or discussed in
.BR PAPI_native(3)
.LP
.I EventCode
-- the numeric code for the event
.LP

.SH RETURN VALUES
On success, these functions return
.B "PAPI_OK."
 On error, a non-zero error code is returned.

.SH ERRORS
.TP
.B "PAPI_EINVAL"
One or more of the arguments is invalid.
.TP
.B "PAPI_ENOTPRESET"
The hardware event specified is not a valid PAPI preset. 
.TP
.B "PAPI_ENOEVNT"  
The hardware event is not available on the underlying hardware. 

.SH EXAMPLES
.nf
.if t .ft CW
int EventCode, EventSet = PAPI_NULL;
char EventCodeStr[PAPI_MAX_STR_LEN];
char EventDescr[PAPI_MAX_STR_LEN];
char EventLabel[20];
	
/* Convert to integer */

if (PAPI_event_name_to_code("PAPI_TOT_INS",&EventCode) != PAPI_OK)
  handle_error(1);

/* Create the EventSet */

if (PAPI_create_eventset(&EventSet) != PAPI_OK)
  handle_error(1);

/* Add Total Instructions Executed to our EventSet */

if (PAPI_add_event(EventSet, EventCode) != PAPI_OK)
  handle_error(1);
.if t .ft P
.fi

.SH BUGS
These functions have no known bugs.

.SH SEE ALSO
.BR PAPI_presets "(3), " PAPI_native "(3), " 
.BR PAPI_enum_events "(3), " PAPI_add_event "(3), " 
.BR PAPI_remove_event "(3), " PAPI_get_event_info "(3)"

